Apply 2bndy5's review suggestion: use single git -c user.name=X -c user.email=Y commit
instead of separate git config + git commit. This avoids polluting the global git
configuration in the CI environment.

- docs/permissions.md: Add warning about GITHUB_TOKEN not triggering CI
  on auto-fix commits, with PAT workaround. Add warning about
  third-party fork PRs where auto-fix cannot work.
- action.yml: Add intelligent fork-detection in push failure warning
  (checks for 403/refused/permission errors and shows context-aware
  message referencing docs).
- .github/workflows/examples/auto-fix.yml: Add comment about PAT
  option for CI re-triggering.

Add configurable git identity for auto-fix commits to address 2bndy5's
concern about commit author reflecting the token owner.

- auto-fix-git-user: custom git username for the auto-fix commit
  (defaults to GITHUB_ACTOR)
- auto-fix-git-email: custom git email for the auto-fix commit
  (defaults to GITHUB_ACTOR_ID+GITHUB_ACTOR@users.noreply.github.com)
- When empty, falls back to GITHUB_ACTOR/GITHUB_ACTOR_ID based values

Co-authored-by: Xianpeng Shen <xianpeng.shen@gmail.com>

Address review feedback on the auto-fix flow:

- Gate the PR-branch checkout and the auto-commit/push steps to
  same-repository pull requests. Fork PRs previously hard-failed the
  checkout (the fork's branch isn't on origin) and could not push; now
  they are skipped with a warning.
- Guard against tag refs: compute the destination branch from the PR
  head ref or a pushed branch ref, and skip otherwise so we never push
  HEAD to refs/heads/<tag> and create a stray branch.
- Stage only tracked modifications with `git add -u` instead of
  `git add -A`, so unrelated untracked/generated files are not swept
  into the auto-fix commit.
- docs/permissions.md: clarify the write permission is for the
  actions/checkout token, and correct the `[skip ci]` guidance (it only
  matters for PAT/App-token pushes, since the default GITHUB_TOKEN push
  does not trigger CI anyway).
- Example workflow: downgrade `pull-requests: write` to `read` (the
  example uses no review/thread-comment feature; `read` is still needed
  for files-changed-only on pull_request events).

I would like to change the default clang-format commit message and leave "refactor: apply clang-tidy fixes" for clang-tidy in the futhure if we also support auto-fix for it

Co-authored-by: Xianpeng Shen <xianpeng.shen@gmail.com>

Two places said something the implementation does not do.

The README told everyone to tag the commit with `[skip ci]` to stop it
re-running CI, but the example above it checks out with the default
`GITHUB_TOKEN` -- which cannot start a workflow run at all, so there was
nothing to skip. docs/permissions.md already had this right and the two
contradicted each other. The tip now names the token that makes `[skip
ci]` meaningful and points at the permissions page for both setups.

`auto-fix`'s own description implied it rewrites whole files. It does
not: cpp-linter assembles range-aware args, so `lines-changed-only`
narrows what gets reformatted. That matters, because with it enabled a
file can come back from auto-fix still failing a whole-file
`.clang-format` check -- worth saying out loud rather than leaving to be
discovered.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

- permissions.md: new "GitHub App token" section (App permissions,
  create-github-app-token, pass the token to checkout and cpp-linter);
  the CI re-trigger note points at it instead of recommending a PAT
- fork note: fork pull requests get no secrets, so an App token or PAT
  cannot help there; auto-fix stays skipped
- README tip and example workflow updated to match
- docs/action.yml: auto-fix inputs land in 2.22.0, not 2.19.0

Co-authored-by: Brendan <2bndy5@gmail.com>

Give the GitHub App token setup its own section under Usage instead of
only a passing mention in the auto-fix tip -- it applies to every feature
and needs no server to host webhooks.

Also add the relative link refs for permissions-doc and app-token-doc to
docs/index.md, which includes the README; without them those links
rendered as literal text on the docs homepage.

Co-authored-by: Brendan <2bndy5@gmail.com>

Co-authored-by: Xianpeng Shen <xianpeng.shen@gmail.com>

Re-applies the action.yml part of 8580162, which was dropped when the
branch was rewritten.

- On pull_request events check out the PR head commit only when HEAD is
  the merge commit, without --force; a dirty tree or a failed checkout
  skips auto-fix with a warning instead (actions/checkout provides
  refs/pull/N/merge, so committing there would push that merge into the
  branch)
- Stage only modified files matching the configured `extensions` and
  count `git ls-files --modified` output instead of parsing an exit code

…kflow

On pull_request events actions/checkout provides refs/pull/N/merge, so
the action used to switch the workspace to the head commit itself. That
silently changes the tree every later step sees. Drop the step and make
the workflow responsible instead, the way git-auto-commit-action does:
document `ref: ${{ github.event.pull_request.head.sha }}` on
actions/checkout (head.sha rather than head_ref so fork PRs still check
out), and have the commit step verify HEAD == head.sha on pull_request,
skipping with a warning that names the missing input otherwise.

Adds a job that runs the action with auto-fix on the demo sources and
asserts the resulting commit: message, author and email from the inputs,
only files under docs/examples/demo, a clean tree afterwards and zero
clang-format findings. The job has no push credentials, so the push is
rejected by design and the last step checks the commit never reached the
PR branch.

Drop `ref` so the job covers the action's own checkout of the PR head,
and skip the job on fork pull requests, where auto-fix makes no commit.